home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sources / libxpm / libxpm34.gz / libxpm34 / xpm-3.4 / README < prev    next >
Text File  |  1994-03-14  |  6KB  |  169 lines
  1. ** Copyright 1989-94 GROUPE BULL -- See license conditions in file COPYRIGHT **
  2.  
  3.                 XPM Version 3
  4.  
  5. WHAT IS XPM?
  6. ============
  7.  
  8. XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
  9.  
  10. Here is provided a library containing a set of four functions, similar to the
  11. X bitmap functions as defined in the Xlib: XpmCreatePixmapFromData,
  12. XpmCreateDataFromPixmap, XpmReadFileToPixmap and XpmWriteFileFromPixmap for
  13. respectively including, storing, reading and writing this format, plus four
  14. other: XpmCreateImageFromData, XpmCreateDataFromImage, XpmReadFileToImage and
  15. XpmWriteFileFromImage for working with images instead of pixmaps.
  16.  
  17. This new version provides a C includable format, defaults for different types
  18. of display: monochrome/color/grayscale, hotspot coordinates and symbol names
  19. for colors for overriding default colors when creating the pixmap. It provides
  20. a mechanism for storing information while reading a file which is re-used
  21. while writing. This way comments, default colors and symbol names aren't lost.
  22. It also handles "transparent pixels" by returning a shape mask in addition to
  23. the created pixmap.
  24.  
  25. See the XPM Manual for more details.
  26.  
  27. HOW TO GET XPM?
  28. ===============
  29.  
  30. New xpm updates are announced on the comp.windows.x newsgroup, and on the
  31. "xpm-talk" list. All new "official" xpm releases can be found by ftp on:
  32.  
  33.     ftp.x.org          (18.112.44.100) contrib     (Boston, USA)
  34.     avahi.inria.fr     (192.5.60.47) pub     (Sophia Antipolis, France)
  35.  
  36.  
  37. DOCUMENTATION:
  38. =============
  39.  
  40. Old users might read the CHANGES file for a history of changes interesting
  41. the user.
  42.  
  43. Read the doc. The documentation is in PostScript format (file doc/xpm.ps) and
  44. has been produced with FrameMaker. The source files are available on request.
  45.  
  46.  
  47. INSTALLATION:
  48. ============
  49.  
  50. To obtain the XPM library, first uncompress and untar the compressed tar file
  51. in an approriate directory.
  52.  
  53. Then you can either compile xpm via "imake" or in a stand-alone way.
  54.  
  55. WITH IMAKE:
  56.  
  57.     Imakefiles are provided to build both shared and unshared libraries.
  58.     First have a look at the beginning of the lib/Imakefile and see if you
  59.     need to do some modification to fit with your system.
  60.     You should know how to use imake to build the XPM Makefiles
  61.     by executing "xmkmf", then do:
  62.  
  63.         make Makefiles
  64.         make depend        (if you want to)
  65.         make
  66.  
  67.     which will build the XPM library and the sxpm application. 
  68.     Then do:
  69.  
  70.              make install
  71.         make install.man
  72.  
  73.     which will install the library and the sxpm pregram and man page.
  74.  
  75.     If it fails, you may edit the Imakefiles to add compilation flags to
  76.     suit your machine.
  77.  
  78. WITHOUT IMAKE:
  79.  
  80.     To compile xpm, in the xpm directory you just created, do:
  81.  
  82.             make -f Makefile.noXtree
  83.  
  84.     Then to install it, do:
  85.  
  86.         make -f Makefile.noXtree install
  87.  
  88. SXPM:
  89. ====
  90.  
  91. In addition to the library the sxpm tool is provided to show XPM file and
  92. convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
  93. 'make' or 'make all' you should have it yet, otherwise just do:
  94.  
  95.               cd sxpm; make
  96.  
  97. This application shows you most of the features of XPM and its source can be
  98. used to quickly see how to use the provided functions.
  99.  
  100. By executing 'sxpm -help' you will get the usage.
  101.  
  102. Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
  103. function. The pixmap is created from the static variable plaid defined in the
  104. sxpm.c file. sxpm will end when you press the key 'q' in the created window.
  105.  
  106. Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
  107. overriding color symbols giving a colorname, executing 'sxpm -sp lines_in_mix
  108. 1' will show overriding giving a pixel value, and executing 'sxpm -plaid -cp
  109. red 0' will show overriding giving a color value.
  110.  
  111. Then you should try 'sxpm -plaid -o output' to get an output file using the
  112. XpmWriteFileFromPixmap function.
  113.  
  114. You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
  115. get the pixmap printed out on the standard output with colornames instead of
  116. rgb values.
  117.  
  118. Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
  119. and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
  120.  
  121. The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
  122. flag to show the utility of this one. Indeed, compare the color section of the
  123. two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
  124. plaid.xpm -o bar'. All the default colors and also the comments have been
  125. restored.
  126.  
  127. To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
  128. extensions are handled.
  129.  
  130. Of course, other combinations are allowed and should be tried. Thus, 'sxpm
  131. plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
  132. to a XPM version 3 using sxpm.
  133.  
  134. See the manual page for more detail.
  135.  
  136. OTHER TOOLS:
  137. ===========
  138.  
  139. Several converters dealing with XPM and a pixmap editor can be found in the
  140. xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
  141. general image operations such as scaling, resizing, dithering, and to convert
  142. from and to any other image format.
  143.  
  144. DISCUSSION:
  145. ==========
  146.  
  147. There is a mailing list to discuss about XPM which is xpm-talk@sophia.inria.fr.
  148. Any request to subscribe should be sent to xpm-talk-request@sophia.inria.fr.
  149.  
  150. COPYRIGHT:
  151. ==========
  152.  
  153.   Copyright 1989-94 GROUPE BULL --
  154.   See license conditions in the COPYRIGHT file of the XPM distribution
  155.  
  156. Please mail any bug reports or modifications done, comments, suggestions,
  157. requests for updates or patches to port on another machine to:
  158.  
  159. lehors@sophia.inria.fr        (INTERNET)
  160.  
  161. 33 (FRANCE) 93.65.77.71        (VOICE PHONE)
  162.  
  163. Arnaud Le Hors            (SURFACE MAIL)
  164. Bull c/o Inria BP. 109
  165. 2004, Route des lucioles
  166. Sophia Antipolis
  167. 06561 Valbonne Cedex
  168. FRANCE
  169.